matRiks: An R package for the automatic generation of rule-based matrices

Few resources are available for the automatic generation of Raven-like matrices. Some of them are no longer working, while others are hardly customizable without adavnced programming skills. Although an R package exists for generating stimuli for psychological assessments, it is currently confined to create rotation of the same shape. The matRiks package has been developed with the aim of overcoming the above mentioned issues. This package generates matrices according to dufferent types of rules, from the most basic ones based on the visuo spatial features of the figures to the most complex ones, based on inferential and inductive reasoning. This unveils the possibility of generating new customizable stimuli and of systematically manipulating the complexity of the stimuli. Being developed within the R environment, the matRiks package is completely open-source, allows for the reproducibility of the stimuli, and it can be easily used by people with basic knowledge of the R language.

1 Introduction

Cattell (1963) defined fluid intelligence (g) as the ability of solving novel reasoning problems that has little to do with concepts learned in schools or through acculturational processes. The adjective “fluid” explicitly refers to its ability to “flow” into a variety of tasks and cognitive activities (Horn, 1972). Given this definition of fluid intelligence, it appears natural that the instruments used for its evaluation tap on the respondent’s ability to solve abstract problems that involve acculturation as little as possible, such as figural analogies, figure classifications, matrices, and number and letter series (Horn, 1968).

The Raven’s progressive matrices (RPM, Raven (1938)) are among the most famous tools for the assessment of g. The RPM consists in a series of non-verbal multiple-choice stimuli where respondents are required to complete a series of drawings composed of different figures by identifying the relevant features that rule the relationships between the figures. These drawings are often referred to as matrices. To pursue this aim, the respondents must choose the figure that complete the drawing among a list of other figures, the so-called distractors. This task should measure the ability of the respondents to identify and take into account the features (also called “rules”) that govern the relationship between the figures to compose the drawing. Different versions of the RPM exist, according to the target population (i.e., children with less then 12 years of age or adults) to which they are administered. The Colored Progressive Matrices (CPM, cit) are composed of sets of \(2\times2\) matrices (i.e., 4-cell matrices), some of which (CONTROLLARE) includes colored figures. The advanced progressive matrices (ADM, cit) are composed of sets of \(3\times3\) matrices meant for assessment in gifted population (DIRE MEGLIO). Finally, the RPM are meant for the assessment among the general population and are composed of both \(2\times2\) and \(3\times3\) matrices. The colored figures are presnt only in the CPM.

The RPM and similar tasks (here denoted as Raven-like matrices or Raven-like tasks) are employed in different fields, from clinical evaluation of intelligence to the selection processes in organizational psychology (citation needed). Since Raven’s and Raven-like tasks involve the ability to solve new abstract problems, the stimuli composing these tasks should not be spread among the general population to preserve the novelty of the tasks. The rules that govern the relastionhsip between the figures of a matrix can also be used to generate new stimuli, and different resources have been developed throuought the years with this specific aim, such as Sandia (cit), Corvus (cit), and the R package Imak (cit).

The stimuli generated with Sandia have been analysed in an Item Response Theory framework to validate them as a test for measuring fluid intelligence. The stimuli are available upon request to the authors, however no new stimuli can be generated because the code on which Sandia is based is no longer maintained. Corvus represents another possible resource for generating Raven-like tasks. Corvus is written in Javascript but the Author provided a nice and easy-to-use graphical interface where the user can specify the figures and the rule(s) for the generation of the matrices. However, Corvus provides few degrees of freedom in terms of both the figures and the number of rules that can be manipulated through the graphical interface. Any customization from the user, like adding other figures, modifying existing ones, or implementing new rules, require to modify the JavaScript code, which might be quite demanding for people with little to null experience in JavaScript coding. Finally, the ImaK package is an R package that allows for generating visual analogies. The code for generating such stimuli (along with their response options) is quite straightforward and easy to use. However, the stimuli that can be generated with the ImaK package are mostly based on the rotation of the same figure to which some objects can be added or removed. As such, the only rule that is manipulated is the spatial rotation of the figures.

Given the limitations of the existing resources for generating Raven-like tasks, there is the need of an open-source, easy-to-use, and constantly maintained resource for generating such stimuli through the systematic manipulation of rules applied to different figures. The matRiks package (Brancaccio et al. (2023)) has been developed to pursue these aims. The package enables the generation of matrices by manipulating one or multiple rules on one or multiple figures. Additionally, it automatically generates the response list associated with the matrix. Beyond the default settings, the matRiks package allows for the generation of new figures and customization of matrices and response lists. The systematic manipulation of both the rules and the figures for the matrix generation should grant the possibility of grading the granularity of the complexity of the matrices by varying one element at the time. In a similar vein, the package should allow for generating matrices that can be considered equivalent in terms of rules employed for their generation but that differ in terms of figures composing the drawing. In what follows, the term stimulus is used to identify the matrix with its associated response list.

The manuscript is organized as follows. The next section presents the rules that are usually employed in the RPM along with the specific types of error responses (i.e., distractors) that compose the response list associated with a matrix. A complete example of the generation of a stimulus (i.e., the matrix and the associated response list) and some final remarks on the potential applications of this package conclude the presentation. # Background

Rule based matrices

Literature highlights a plethora of rules that can be manipulated for the generation of the Raven-like tasks (cit cit cit). Beyond the fact that some of these rules have different names in different sources but refer to the same manipulation (e.g., the rule defined as “and problem” in Harris el a. 2020 is called “intersection” rule in Arendasy et al. 2005), they can be summarized into different macro-categories, namely visuospatial rules (i.e., the manipulation concerns the graphical and spatial features of the figures, Figure 1), and logical rules (i.e., the manipulation concerns the logical relationships between the figures composing the matrix, Figure 2). The rules can be used to manipulate to different figures to generate a matrix.

Figure 1: Example of visuospatial rule: Changes in size

Figure 2: Example of logical rule: Insiemistic Interscetion AND

In Figure 1, the manipulation concerns a specif feature of the figure, that is its size, and it can be observed as the the figure decreases its size across the cells. The leftmost cell contains the figure with its original size, the middle cell contains a smaller figure, while the rightmost cells contains the smallest one. In Figure 2, the manipulation concerns the relationships between the objects composing the figures, which are combined together according to a logical rule based on the insiemistic intersection of the objects. Specifically, the figure in the rightmost cell results from the intersection between the figures in the leftmost cell and those in the middle cell.

Both visuospatial and logical rules can be manipulated according to directional logic. Specifically, the rules can be applied horizontally (i.e., the manipulation of the rule can be seen across columns but not across rows, H direction), vertically (i.e., the manipulation of the rule can be seen across rows but not across columns, V direction), or diagonally (i.e., the manipulation of the rule can be seen both across columns and across rows). Concerning the diagonal directional logic, it can follow either the main diagonal of the matrix (i.e., the manipulation of the rule can be seen from the top-left corner to the low-right corner, TL-LR direction) or the secondary diagonal of the matrix (i.e., the manipulation of the rule can be seen from the low-left corner to the top-right corner, LL-TR direction).

The response options

A large corpus of literature has investigated the role of the distractors in the response processes involved when solving the Raven matrices, focusing on the specific error responses chosen by the respondent (Forthmann et al. (2020), Kunda et al. (2016), Storme et al. (2019)). The underlying logic is that the incorrect response is not chosen at random by the respondent, but it can be the result of an educated guess, or it can be chosen because the respondent is misled by a specific feature. In other words, the incorrect responses might reflect an incorrect solution strategy resulting in the choice of a specific type of distractor over another one (Kunda et al. 2016). The distractors can be classified according to the incorrect response strategy they represent. Kunda et al. (2016) present a list of criteria for the identification of the distractors in the SPM based on classification of the error types from the CPM and APM manuals (Raven and Raven 2004). The distractor that is chosen in place of the correct response option can be collected into four main four conceptual errors: (i) Repetition (R) errors occur when the chosen response option is a cell adjacent to the blank space, (ii) Difference (D) errors occur when the chosen response option is completely different from any entry of the matrix, (iii) Wrong Principle (WP) errors occur when the chosen response option follows rules other than the ones used in the matrix, and (iv) Incomplete Correlate (IC) errors occur when the chosen response option is in fact the correct response with a variation on a single feature.

Difference errors occur when the chosen response option is completely different from any entry of the matrix. Wrong principle errors occur when the chosen response option follows rules other than the ones used in the matrix. Incomplete Correlate errors occur when the chosen response option is in fact the correct response with a variation on a single feature. Each of the four main error types can be further described by their subcategories.
Table 1 summarizes the definitions of the error types.

Table 1: Taxonomy of error types

Distractors	Definition	Specific Error	Specific definition
Repetition (R)	Entries of the matrix adjacent to the blank cell	R-Left	Repetition of the cell left to the blank space
		R-Top	Repetition of the cell above to the blank space
		R-Diag	Repetition of the cell right to the blank space
Difference (D)	Combination of all the entries of the matrix or the combination of some of their features. It is different from any entry of the matrix and from the other distractors.	D-Blank	Filled completely white or black
		D-Union	Some elements of one entry are emphasized
		D-Plus	Some entries of the matrix are combined together
		D-Diff	Qualitatively different from any other distractor and any entry of the matrix, resulting in a pop-out effect.
Wrong Principle (WP)	Copy or combination of the matrix entries according to another rule	WP-Copy	Repetition of a cell non adjacent to the blank space
		WP-Flip	Rotation or refection of one entry of the matrix.
		WP-Matrix	Transformation or combination of some entries of the matrix or of their elements
Incomplete Correlate (IC)	Correct response with a variation on only a single feature.	IC-Neg	Negative of the correct response
		IC-Fill	Correct response with a different texture or style.
		IC-Flip	The elements of the correct response are displayed with a different layout
		IC-Layout	Elements of the correct response with different proportion or different size of the correct response.
		IC-Scale	Correct response with a different number of elements (small layout changes are allowed)
		IC-Num	Correct response with a missing element.
		IC-Inc	Repetition of the cell left to the blank space

The criteria for the classification of the error types were used for the formal definition and generation of the distractors implemented in the matRiks package. SIAMO SICURI CHE QUESTA ROBA VADA QUI? These criteria were included in the response options operator with the aim of providing the user with a response list composed of 11 elements (ten distractors and the correct response) among which they could choose the most appropriate ones. Specifically, the response options operator generates a response list composed of the correct response, three reptition distractors, one difference distractor, two wrong principle distractors, and four incomplete correlate distractors. Further details on the formal definition of each of the distractors and on their generation are given in the “Generation of the response list” Section.

2 The matRiks package

The matRiks package (Brancaccio et al. 2023) can generate \(2 \times 2\) and \(3 \times 3\) Raven-like matrices with their corresponding set of responses (i.e., the correct response and all the distractors described in the Generation of response list section). The Raven-like matrices are generated according to either visuospatial or logic rules, which can be concatenated with three different directional logic, namely vertically, horizontally, and diagonally. Finally, it is possible to print the generated matrices and set of distractors as either single images (i.e., each cell of the matrix and each distractor are printed separately) or as a complete figure with the set of single distractors.

2.1 Installation

The matRiks package is available on CRAN and can be installed as:

install.packages("matRiks")

The code vignette(package ="matRiks") allows for obtaining the list of all the vignettes included in the package, which illustrates the default figures included in the package and a basic example of its application. Each vignette can be accessed via vignette("vignette-name", package="matRiks"). For instance, the code vignette("generate_matriks", package ="matRiks") opens the vignette that contains the instruction on how to generate an RMarkdown file where both the matrix and its associated response options are plotted together.

2.2 Definition of figures

The matRiks package contains several default figures that can be used for the generation of the matrices and of new figures. All figures have class figure and they are defined as functions, such that the syntax figure_name() must be used to draw them and visualize their structures. The arguments that can be modified inside the parentheses might vary from figure to figure, and they allow for changing different features. The default features of the figures are stored in a list of length 15, and they might vary from figure to figure although the length is unchanged. The features of the figures are defined inside of the list as follows:

• shape: character, the name of the figure
• size.x: numeric, the length of the semi-major axis of the ellipse within which the figure is inscribed (see the documentation of the DescTools for further details)
• size.y: numeric, the length of the semi-minor axis of the ellipse within which the figure is inscribed (see the documentation of the DescTools for further details)
• theta.1: numeric, radiants of the rotation of the circle
• theta.2: numeric, radiants of the rotation of the circle
• rotation: numeric, radiants of the rotation of the ellipse within which the figure is inscribed
• pos.x: numeric, the position on the x-axis
• pos.y: numeric, the position on the y-axis
• lty: integer, the line type of the margins of the figure
• lwd: integer, the width of the margins of the figure
• num: numeric, it is equal to 1 if the figure is draw inscribed into an ellipse, and it equal to 2 if the figure is draw as a arc of a circle
• nv: integer, the number of vertices of the figures (might vary from 2 – lines – to 100 – circle and ellipse –)
• shade: character, the filling of a figure (can also be NA –empty figure–)
• visible: integer, the visibility of the figure
• tag: character, properties of the figure used for the definition of the distractors

The draw function is designed to print all the figrues, as well as the matrices and the response list. To print a figure, the only argument neede inside of the draw function is the name of the figure. For instance, a simple square (Figure @ref{fig:square}) can be printed with the command line:

draw(square())

Figure 3: A simple square

The figures in matRiks are summarized in different categories (e.g., closed figures, black figures, lines), for each of which a vignette lists all the figures. The following types of figure are available in the matRiks package:

Figure Category	Example	Figure Category	Example	Figure Category	Example
Black figures		Flower figures		Other figures
Circle sections		Eight-shaped figures
Closed figures		Lines

Figure 4: Black figures

Figure 5: Circle sections

Figure 6: Other figures

Figure 7: Closed figures

Figure 8: Eight-shaped figures

Figure 9: Flowers figures

Figure 10: Lines

2.3 Concatenation of figures

Other then the pre-existing figures, the matRiks package allows for the generation of new figures by concatenating the existing ones. The cof() (Concatenation Of Figures) function is designed for this aim. The arguments of the cof() function are the names of the default figures presented in the previous section.

For instance, the figure in Figure 11 is obtained by concatenating a circle() and a dot().

eye <- cof(circle(), dot()) # create the new figure eye by concatenating the circle and the dot
draw(eye)

Figure 11: Example of concatenation of circle and dot to obtain an eye-like figure.

The resulting figure eye is a named list of lists of class figure. However, the two original figures are still available and can be considered as separate figures, and as such the object eye is considered a concatenation of two figures.

eye$shape

[1] "circle" "dot"   

Function cof() has also two optional arguments, namely single and name, which allow for the generation of new figures. If set to TRUE , the first argument forces the outcome of the concatenation to be considered as a new single figure, while the second argument defines a new name for such a figure. The following code recreated the figure in Figure \(\ref{fig:eye}\) but it forces the new figure to be a single figure named “eye”.

s_eye <- cof(circle(),dot(),single = TRUE, name = "eye")
s_eye$shape

[1] "eye"

Although this difference is trivial from a graphical standpoint (the single figure and the concatenation of two distinct figures appear exactly the same), it is relevant for the application of some of the rules that require a minimum number of figures for their application (e.g., inferential rules).

MI SONO FERMATA QUI CON LE MODIFICHE 24/10/2024

2.4 Available rules and matrix generation

The function mat_apply(Sq1, hrules="identity", vrules ="idenity", mat.type=9) is the main function for the generation of matrices based on rules and returns an object of class matriks. This function allows for the generation of matrices of different dimension, either 4-cell or 9-cell matrices. The dimension of the matrix can be specified with the argument mat.type, such that mat.type = 4 results in 4-cell matrices (Table 2)

Table 2: Table 3: Four-cell matrix

Sq1	Sq3
Sq2	Sq4

and mat.type = 9 results in 9-cell matrices (default, Table Table 4).

Table 4: Nine-cell matrix

Sq1	Sq4	Sq7
Sq2	Sq5	Sq8
Sq3	Sq6	Sq9

The Sq1 argument defines the starting figure (i.e., the figure to be plotted in the first cell Sq1), which can also be a concatenation of figures. The arguments hrules and vrules allow for the definition of the directional logic with the rule(s) is applied, such that the rules specified in hrules are manipulated horizontally and those specified in vrules are applied vertically.

The application of the mat_apply() function results in an object of class matriks, which is a named list. The length of the list vary as the dimension of the matrix varies, such that it has length 7 when mat.type =4 and of length 12 otherwise. Regardless of the length of the list, it contains the characteristics of the matrix. the following example is based on a 9-cell matrix where the identity rule was applied both horizontally and vertically:

 [1] "Sq1"      "Sq2"      "Sq3"      "Sq4"      "Sq5"      "Sq6"     
 [7] "Sq7"      "Sq8"      "Sq9"      "hrule"    "vrule"    "mat.type"

In particular, Sq1 to Sq9 are lists containing the figures for each of the nine cells composing the matrix, while hrule, vrule, mat.type are vectors containing the rules applied the rules applied horizontally, vertically, and the dimension of the matrix, respectively. Since this is a 9-cell matrix, the list is of length 12 and it contains the cells from Sq1 to Sq9. If a 4-cell matrix is generated, then the list if of length 7 and it contains the cells from Sq1 to Sq4, along with hrule, vrule, mat.type .

The rules are methods that transform a feature of the figure to obtain a different figure or a figure with a modified feature. The matRiks package implements several rules, each of which may be classified differently. The table contains all the rules available in the package, their descriptions, and classifications.

[Rule table ]

As already mentioned, the rules can be classified into visuospatial and logical rules. Such macro classification may have an impact on the difficulty of the generated matrix [cita]. By the way in which the rules have been defined in the matRiks package, they can be either incremental or permutational rules.

The operation underlying the functioning of the incremental rules is the increment of a fixed quantity. Incremental rules apply a fixed increase (or decrease) on each cell of the matrix to obtain the feautures of the figure in the following cell, starting from the first cell. The order in which the fixed increase (decrease) is applied depends on the directional logic used for the generation of the matrix. For instance, Figure 12 illustrates the application of the change in size rule on a square. the change in size rule is an incremental rule, in which the size of the square decreases of a fixed quantity in each subsequent object according to a directional logic.

Figure 12: Example of size rule transformation along a row.

The incremental aspects appear because the squares are smaller compared to the ones on their right but larger than the ones on their left. Hence, by changing the position of any figure in the row the results would not necessarily respect the definition of the rule.

The operation underlying the functioning of the permutational rules is the permutation of the figures (or of their features) across the cells according to a directional logic. For instance, the change in shapes rule is a permutational rule where the objects shown in each cell of the matrix are permuted following an order that is consistent with the directional logic. For instance, consider a matrix where a set of three figures (hexagon(), pentagon, square) are manipulated according to the shape rule following an horizontal directional logic (Figure 13).

Figure 13: Example of shape rule transformation along a row.

By default, the order of the figures is the order with which the figures are concatenated in the starting set. If the order of the figures in the original set is changed, then the rule will adapt and the result will be consistent with the new starting order.

All the rules functions are characterized by three arguments, namely fig,n, and rules. The fig argument defines the initial figure that will be transformed. The n argument defines the position of the resulting figure in the cell, in particular the number of rows or columns (depending on the directional logic) in which the outcome will be displayed. Finally, the rules argument is a vector of characters that defines the type of rule. In particular, if the vector rules contains the strings inv the default order is reversed, and it is denoted that the rule is applied reverse. For instance, to reverse the change in size in Figure (fig:incremental), the code mat_apply(square(size.x=10), hrules = "size.inv") should be used. Figure 14 depicts the resultin sequence of squares.

Figure 14: Example of incremental rule with reverse application: Change in size

The reverse application of the rules can be done with permutational rules as well. By starting with the same set of figures as the one used to generate Figure 13, the sepcification of the argument hrules = "shape.inv" would result in a reverse ordering of the figures across the cells (Figure 15).

Figure 15: Example of permutational rule with reverse application: Change of shape

Even though rules are applied to a single figure their purpose is to be cohesive inside a matrix to allow the participant the correct options responses.

Logical rules AND, OR and XOR are a special case of incremental rules. Specifically, these rules cannot be applied in reverse.

Figure @ref(fig:??) shows the flowchart of the generative procedure underlying mat_apply(). The procedure consists of three serial steps. For the sake of simplicity, they will be illustrated for the 9-cell matrices only. A similar line of reasoning can be applied to 4-cell matrices.

The first step is to generate the named list of all the cells from Sq1 to Sq9. Each of the cells contains the initial figure defined in Sq1. No rule has still been applied. For instance, considering the concatenation of figure cof(square(), circle(),dot()) plotting the outcome of this step will result in the following matrix:

Figure 16: Example of outcome of the first step of the mat_apply procedure.

Since the application of the logical rules requires a well-defined relationship between the cells of the matrix, the second step checks whether arguments hrules or vrules contain a logical rule. If so, the procedure throws an error. An error is thrown whenever the application of a logical rule is combined with the application of a visuospatial rule, a logical rule is used for the generation of a 4-cell matrix, or if two different logical rules are applied concurrently to the same figures with different directional logic. If only one single logical rule is applied and none of the above error-condition has been met, the procedure will generate the whole matrix in a single step.

If the test of the second step turns out to be false, the procedure enters in the third step. In this step, the rules specified in hrules are applied following the horizontal directional logic (i.e., the rules are iterated among the elements horizontally.

The fourth step applies the rules specified in vrules following the vertical directional logic (i.e., the rules are iterated among the elements horizontally).

Since the third and forth steps are made one after another using the same rule, for instance size, both with a horizontal a vertical logic, the two transformation on the cells ends up to cumulate. For instance, considering the code mat_apply(square(),hrules="size", vrules="size"), at the end of the third step the figure in Sq5 will be half the size of Sq1. During the forth the size of Sq5 will be halve again resulting in a figure that is a quarter of the initial Sq1.

It is worth mentioning that the combination of the same rule horizontally and vertically ends up in the definition of a diagonal directional logic. In particular, if the same rule is applied in reverse in one direction and applied direct in the other, it will result in a TL-LR directional logic. On the other hand if the same rule is direct (or reverse) in both horizontal and vertical directional logic they will give rise to a LL-TR logic.

RIPRENDO DA QUI 24/10/2024

2.5 Concatenation of matrices

The com() (Concatenation Of Matrices) function allows for combining and layering different matrices together to generate a multi-layer matrix.

Figure 17 and Figure 18 depict a matrix created by manipulating the same set of rules. Specifically, two rules are manipulated horizontally (i.e., shade and shape) and one rule is manipulated vertically (i.e., `rotate``). As such, the figures in the cells and the shading change across columns, while the rotation of the figures change across rows.

Figure 17: Single-layer matrix with two rules manipulated horizontally (Shape and filling) and one rules manipulated vertically (Orientation)

Figure 18: Multi-layer matrix with two rules manipulated horizontally (shape and filling) and one rule manipulated vertically (orientation)

The matrix depicted in Figure 17 results from the manipulation of the set of rules to obtain a single-layer matrix, such that all rules are concurrently applied to the same set of figures (i.e., hexagon(), square(), pentagon()). The same set of rules is manipulated to obtain the matrix in Figure 18. However, the three rules are manipulated to obtain three different single-layer matrices, one for each rule (Figures 19, 20, and 21), which are then concatenated together. Each of these single-layer matrices can be considered as a layer of the multi-layer matrix. The layering of the matrices moves from the background (considered as external) to the foreground (considered as internal). Layers are counted inwards \(m = 1, \ldots, M\) (where \(M\) is the total number of matrices to concatenate), such that the background matrix is layer 1 and the foreground matrix is layer \(M\). The matrix in Figure @(fig:multi-layer) is composed of \(M = 3\) layers: (1) background layer obtained with horizontal manipulation of the shape rule (Figure 19), (2) middle layer obtained with vertical manipulation of the rotate rule (Figure 20, and (3) foreground layer obtained with horizontal manipulation of the shade rule(Figure ??).

Figure 19: Layer 1 (Background matrix)

Figure 20: Layer 2

Figure 21: Layer 3 (Foreground matrix)

The com() function concatenates the single-layer matrices to obtain the multi-layer one:

com(multi_a, multi_b, multi_c)

The matrices have to be concatenated hierarchically from the background layer to the foreground layer The hierarchy between the layers is of the uttermost importance for definition of the distractors, specifically for the generation of the incomplete correlate ones. Generally, the manipulation of the correct response to obtain the incomplete correlate distractors is applied to the figures in the foreground layer \(M\). Further details on the definition and on the generation of the incomplete correlate distractors of multi-layer matrices are given in section Response list.

Generation of the response list

The generation of the distractors composing the response list is constrained to: (i) the type of matrix (i.e., single-layer matrix vs. multi-layer matrix), (ii) the rule(s) manipulated for the matrix generation, and (iii) the directional logic of the rule manipulation. To the best of our knowledge, there is not a formal definition of the specific features of each distractor and on their applicability given the above-mentioned constrained.
As such, the development of the response option operator required the formal definition of the distractors and of all the possible exceptions given the constraints imposed by the matrices generated via the matrix operator. The definitions of the distractors implemented in the matRiks package is reported in Table 5 .

Table 5: Definition of the distractors implemented in the matRiks package for \(3 \times 3\) and \(2 \times 2\) matrices

Distractors	\(3 \times 3\) matrices	\(2 \times 2\) matrices
R-Left	SQ8	SQ3
R-Top	SQ6	SQ2
R-diag	SQ5	SQ1
Wp-Copy	SQ1 or SQ3	SQ1
WP-Matrix	SQ1 or SQ3 with the superimposition of another cell.	SQ3 or SQ2 with the superimposition of the rotation of WP-Copy
Difference	SQ1 or SQ3, SQ4, SQ7 with the superimposition of a figure which is not manipulated in the matrix.	SQ3 or SQ1 with the superimposition of a figure that is not manipulated in the matrix
IC-Inc	It is the correct response with a missing element	Same as \(3\times 3\) matrices
	Single-Layer: Not possible	Same as \(3\times 3\) matrices
	Multi-layer: The most internal figure is removed from the correct response.	Same as \(3\times 3\) matrices
	Logic matrices: The element that is removed is randomly selected.	Same as \(3\times 3\) matrices
IC-Neg	Color inversion of the correct response (single-layer matrix) or of one of its figures (multi-layer matrix)	Same as \(3\times 3\) matrices
	Single-layer matrix: Color inversion of the figure in the correct response	Same as \(3\times 3\) matrices
	Multi-layer matrix: Color inversion of the most internal figure of the correct response	Same as \(3\times 3\) matrices
IC-Flip	Rotation or reflection of the correct response (single-layer matrix) or of one of its figures (multi-layer matrix)	Same as \(3\times 3\) matrices
	Single-layer matrix: Reflection/Rotation of the figure in the correct response	Same as \(3\times 3\) matrices
	Multi-layer matrix: Reflection/Rotation of the most internal figure of the correct response	Same as \(3\times 3\) matrices
IC-Scale	Resize of the correct response (single-layer matrix) or of one of its figures (multi-layer matrix)	Same as \(3\times 3\) matrices
	Single-layer: Resize of the figure in the correct response	Same as \(3\times 3\) matrices
	Multi-layer matrix: Only the most internal figure in the correct response is resized	Same as \(3\times 3\) matrices

The response option operator (implemented in the response_list() function) runs through different steps. First, it checks for the number of rules and the directional logic with which that have been manipulated, as well as whether the matrix is a single matrix or a multi-layer matrix. This check is crucial for the generation of the incomplete correlate distractors, but not for the other tyoes of ditsractors (i.e., R, WP, and D) since they are generated by considering the figures in a cell as a single figure. Conversely, since the IC distractors are a moficiation of a single feature of the correct response, there is the need to determine whether they can be generated in the first place and, if so, on which element of the correct response the change should be applied.

In single-layer matrices, the IC-inc distractor cannot be generated given that it requires the removal of an element of the figure, while all other IC distractors can be generated, unless a figure with specific tags is employed. For instance, the s-shaped figures such as the miley() cannot change color, and, as such, the “shade” tag is not present in their tag list. When the response response option generator does not find the shade tag among the tags of miley() to generate the IC-neg distractor, it throws a warning and the IC-neg distractor is replaced by the correct response canceled out by a black thick cross.

In multi-layer matrices, the IC distractors are generated by modifying the figure in the foreground matrix. Before applying the manipulation, the tags of the figure in the foreground matrix are checked to investigate whether all the IC distractors can be generated from that figure. If this tests false, then the response option generator moves towards the background of the multi-layer matrix, until it finds a figure whose tags satisfy the condition for creating all the IC distractors.

For the generation of WP and D distractors, the choice between using cell SQ1 or cell SQ3 stictly depends on the number of rules and on the directional logic with which they are manipulated. Specifically, cell SQ1 is selected when the matrix is generated via the manipulation of a single rule with V, H, or TL-LR directional logic. If the manipulation of the single rule follows a LL-TR directional logic or two rules are manipulated with all possible directional logic, the SQ3 cell is chosen. This is done to avoid that the WP-Copy distractors can be interpreted as IC distractors. In some instances, the R distractors in \(3 \times 3\) matrices cannot be generated because they are equal to the correct response. For instance, if a matrix is generated with the vertical manipulation of a single rule, the R-Left distractor (SQ8) is equal to the correct response. In such instances, the distractor that is equal to the correct response is generated by the response options operator but it is covered with a thick black cross.

A similar procedure is applied for choosing which cell to use between SQ3 and SQ2 or between SQ3 and SQ1 for the generation of WP-Matrix and Difference distractors in \(2 \times 2\) matrices. In both cases, the choice depends on whether at least one rule is applied both horizontally and vertically. If the same rule is applied both horizontally and vertically, then SQ3 is chosen, otherwise SQ2 and SQ1 are chosen.

The response options operator generates the response list (i.e., the correct response and all the distractor presented in the Table) through the response_list() function, which results in a list of figures that correspond to each of the distractors. For instance, the distractors of the matrix in Figure 17 can be obtained with:

response_list(single_matrix)

The function response_list() results in a named list of length 11 containing all the response options:

 [1] "correct"    "r_diag"     "r_left"     "r_top"      "wp_copy"   
 [6] "wp_matrix"  "difference" "ic_neg"     "ic_flip"    "ic_size"   
[11] "ic_inc"    

and it can be plotted as:

Warning in ic_inc.matriks(obj): IC-Inc cannot be obtained with a
single figure

As it can be noted, a warning has appeared and it refers to the IC-Inc distractor. As per Table 5 ., the distractor IC-Inc is defined as the correct response with a missing element. However, having a single-layer matrix does not allow for the removal of any element, hence the warning “IC-Inc cannot be obtained with a single figure” is thrown and the IC-Inc distractor is replaced by the correct response over which a black thick cross is imposed.

Given that the matrix in Figure 18 is composed of three layers, it is possible to obtain also the IC-Inc distractor:

However, the difference distractor is not well defined. The user can change the random seed for the generation of this distractor with the argument seed(), such that another random figure is chosen among the available ones:

draw(response_list(multi_matrix, seed = 7), 
     main = TRUE)

2.6 A complete example

This section presents a complete example on how to generate a multi-layer \(3 \times 3\) matrix with logical rules and its related response options.

The first layer is generated by manipulating the AND logical rule according to an H directional logic on a square composed of 4 lines:

The second layer is generated by manipulating the OR logical rule according to a V directional logic on a flower composed of 4 petals:

The multi-layer matrix can be composed with the com() function by concatenating the two single-layer matrices:

The response options associated with the multi-layer matrix can be generated with the response_list() function:

Since the filling color the miley cannot be changed, the IC-Neg distractor cannot be generated and the function throws a warning and the ic_neg distractor is replaced by the correct response with the superimposition of a thick black cross. The difference distractor does not look good. The figure that is superimposed to the cell taken from the matrix can be changed by changing the seed in the response_list() function:

Assuming that a response list of length 8 (the correct response along with seven distractors) is associated with the multi-layer matrix, a character vector with the labels of the chosen distractors can be specified directly in the draw function:

3 Summary

This article briefly illustrates the functioning of the matRiks package for the automatic generation of Raven-like stimuli. This package has been developed with the intention of providing the users with a flexible, open-source, and easy-to-use tool for generating Raven-like matrices according to different rules, encompassing both visuo-spatial and logical rules, along with their associated response list.

The rules for generating the matrices and for generating the distractors associated to each matrix that are implemented in the matRiks package derive from vast literature concerning Raven’s matrices and the error patterns observed on the CPM and the APM. As such, this package potentially provide the possibility for generating stimuli that are equivalent in terms of rules and response options to the standard Raven’s stimuli. This allows for a comparison between the responses observed with the standard stimuli and those generated with the package.

This package has been developed within a broader project founded by the Italian Ministry of University and Research, which is aimed at the development of an intelligent system for the adaptive assessment of executive functions and fluid intelligence among general and clinical populations. The test used for assessment of fluid intelligence (named MatriKS) was developed following the principles of Raven’s Matrices. Specifically, the stimuli composing the test have been developed with the matRiks package ((mdpi?)).

This package allows for high degrees of freedom in the generation of matrices with different difficulty. For instance, it allows for the generation of stimuli that combine multiple rules by exploiting the possibility of layering multiple matrices together. Moreover, the high degree of control provided to the users allow them to thoroughly manipulate the difficulty of the matrix, for instance by adding or removing objects and combining together different rules.

The package is regularly maintained and new functions will be available in the future. As such, the users should refer to the official documentation of the package that is constantly updated.

Although the functions implemented in matRiks are quite straightforward and easy to use, they need a basic knowledge of the R language. To overcome this issue and allow for a wider use of the package even among people that are not familiar with R, a web application built with the shiny package ((shiny?)) will be developed in the future.

4 Customizing tooltip design with ToOoOlTiPs

ToOoOlTiPs is a packages for customizing tooltips in interactive graphics, it features these possibilities.

5 A gallery of tooltips examples

The palmerpenguins data (Horst et al. 2020) features three penguin species which has a lovely illustration by Alison Horst in Figure 22.

Figure 22: Artwork by @allison_horst

Table 6 prints at the first few rows of the penguins data:

Table 6: A basic table

species	island	bill_length_mm	bill_depth_mm	flipper_length_mm	body_mass_g	sex	year
Adelie	Torgersen	39.1	18.7	181	3750	male	2007
Adelie	Torgersen	39.5	17.4	186	3800	female	2007
Adelie	Torgersen	40.3	18.0	195	3250	female	2007
Adelie	Torgersen	NA	NA	NA	NA	NA	2007
Adelie	Torgersen	36.7	19.3	193	3450	female	2007
Adelie	Torgersen	39.3	20.6	190	3650	male	2007

Figure 23 shows an interactive plot of the penguins data, made using the plotly package.

p <- penguins %>% 
  ggplot(aes(x = bill_depth_mm, y = bill_length_mm, 
             color = species)) + 
  geom_point()
ggplotly(p)

Figure 23: A basic interactive plot made with the plotly package on palmer penguin data. Three species of penguins are plotted with bill depth on the x-axis and bill length on the y-axis. When hovering on a point, a tooltip will show the exact value of the bill depth and length for that point, along with the species name.

6 Summary

We have displayed various tooltips that are available in the package ToOoOlTiPs.

6.1 CRAN packages used

matRiks, Imak, palmerpenguins, plotly, ggplot2

6.2 CRAN Task Views implied by cited packages

DynamicVisualizations, Phylogenetics, Spatial, TeachingStatistics, WebTechnologies